home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / kernel / dev / devBlockDevice.h < prev    next >
C/C++ Source or Header  |  1992-12-18  |  9KB  |  219 lines
  1. /* 
  2.  * devBlockDevice.h --
  3.  *
  4.  *    Declarations for block devices drivers.  A block device is any device
  5.  *    that provides random access to some number of fixed size units
  6.  *    called blocks. Block device are normally used to build file system
  7.  *    on but may also be accessed like a file. 
  8.  *
  9.  *    The model used for block devices is that devices are first "attached"
  10.  *    to the system.  This is normally done when the device is
  11.  *    opened with Fs_Open. Attaching a device first 
  12.  *    verifies the existence and readiness (i.e. Is it powered on?)
  13.  *    of the device.  If the device exists and is accessible, the
  14.  *    attach routine returns a pointer to a handle use to 
  15.  *    access the device. 
  16.  *
  17.  *    Because of intended usage and the speeds of some
  18.  *    block devices, the I/O interface to block devices is asynchronous.
  19.  *    Input and output operations are started by calling Dev_BlockDeviceIO
  20.  *    that starts the operation and returns before the operation 
  21.  *    completes. The initiator of block input/output operations is
  22.  *    notified of completion by a call back to a function specified
  23.  *    in the request.
  24.  *
  25.  * Copyright 1989 Regents of the University of California
  26.  * Permission to use, copy, modify, and distribute this
  27.  * software and its documentation for any purpose and without
  28.  * fee is hereby granted, provided that the above copyright
  29.  * notice appear in all copies.  The University of California
  30.  * makes no representations about the suitability of this
  31.  * software for any purpose.  It is provided "as is" without
  32.  * express or implied warranty.
  33.  *
  34.  * $Header: /cdrom/src/kernel/Cvsroot/kernel/dev/devBlockDevice.h,v 9.3 91/08/19 13:39:54 jhh Exp $ SPRITE (Berkeley)
  35.  */
  36.  
  37. #ifndef _DEVBLOCKDEVICE
  38. #define _DEVBLOCKDEVICE
  39.  
  40. #include <user/fs.h>
  41.  
  42. /*
  43.  * MAX_BLOCK_DEV_CTRL_WORDS - Number of sizeof(int) words reserved for 
  44.  *                   controller use in a block device request.
  45.  *                  This memory is used by the controller for
  46.  *                  queuing and building controller control blocks.
  47.  */
  48.  
  49. #define    MAX_BLOCK_DEV_CTRL_WORDS (384/sizeof(int))
  50.  
  51. /*
  52.  * The DevBlockDeviceRequest structure is passed to block IO devices to 
  53.  * request a range of address to be read or written.  This startAddress and
  54.  * range must be fit within the constraint specified in the 
  55.  * DevBlockDeviceHandle.
  56.  */
  57. typedef struct DevBlockDeviceRequest {
  58.     int            operation;    /* Operation  FS_READ or FS_WRITE. */
  59.     unsigned int    startAddress;    /* Byte offset into device to start
  60.                      * operation. */
  61.     unsigned int    startAddrHigh;    /* High order 32 bits of byte offset
  62.                      * starting address. */
  63.     int            bufferLen;    /* Length of the data buffer for 
  64.                      * request in bytes. */
  65.     Address        buffer;        /* The data buffer. */
  66.     void        (*doneProc) _ARGS_ ((struct DevBlockDeviceRequest
  67.                                                  *requestPtr,
  68.                                          ReturnStatus returnStatus,
  69.                          int amountTransferred));
  70.                                         /* Procedure to call upon completion.*/
  71.     ClientData        clientData;    /* Word of client data available to the 
  72.                      * caller.  */
  73.                 /*
  74.                  * The rest of the bytes in this structure are
  75.                  * for block device controller information. 
  76.                  * It is declared to be an array of ints to 
  77.                  * guarantee it will start on a word 
  78.                  * boundary. */
  79.     int            ctrlData[MAX_BLOCK_DEV_CTRL_WORDS];
  80. } DevBlockDeviceRequest;
  81.  
  82. /* 
  83.  * An active block device is described by a pointer to it's block device 
  84.  * handle. A block device handle must start with the a DevBlockDeviceHandle 
  85.  * structure. The call sequence of routines in DevBlockDeviceHandle is 
  86.  * defined in the macro specified in the comment following the structure's
  87.  * field names.
  88.  */
  89.  
  90. typedef struct DevBlockDeviceHandle {
  91.     ReturnStatus (*blockIOProc) _ARGS_ ((struct DevBlockDeviceHandle
  92.                                               *blockDevHandlePtr,
  93.                                      DevBlockDeviceRequest *requestPtr));
  94.                                         /* Start a block read or write
  95.                      * operation. 
  96.                      * See below for calling sequence. */
  97.     ReturnStatus (*IOControlProc) _ARGS_ ((struct DevBlockDeviceHandle
  98.                                               *blockDevHandlePtr,
  99.                            Fs_IOCParam *ioctlPtr, 
  100.                        Fs_IOReply *replyPtr));
  101.                         /* Perform an IO Control operation on
  102.                      * the device. 
  103.                      * See below for calling sequence. */
  104.     ReturnStatus (*releaseProc) _ARGS_ ((struct DevBlockDeviceHandle
  105.                                             *blockDevHandlePtr));
  106.                                         /* Release the device and free any
  107.                      * resources held. 
  108.                      * See below for calling sequence. */
  109.     int         minTransferUnit;    /* Smallest unit of transfer to or
  110.                      * from the device. All request must
  111.                      * at least this size and be 
  112.                      * a multiple of this size. */
  113.     int        maxTransferSize;    /* Largest unit of transfer to and 
  114.                      * from the device. */
  115.     ClientData    clientData;        /* A word of clientData usable by the
  116.                      * caller. */
  117. } DevBlockDeviceHandle;
  118.  
  119.  
  120. /*
  121.  * DevBlockDeviceHandle routine releaseProc calling sequence:
  122.  *    
  123.  * releaseProc -
  124.  *
  125.  *    ReturnStatus releaseProc(blockDevHandlePtr)
  126.  *        DevBlockDeviceHandle *blockDevHandlePtr; / * The device handle as
  127.  *                               * returned by the 
  128.  *                               * attach routine. * /
  129.  *    Release the resources in use by the specified device. 
  130.  *    Once released, the device must be attached again with 
  131.  *    attachProc before any operation can be performed.
  132.  *    Note that device attaches do not nest so the caller is 
  133.  *    responsible for insuring all users of a device are finished
  134.  *    before releasing the device. releaseProc returns SUCCESS if
  135.  *    the operation succeeds or a Sprite error code otherwise.
  136.  *
  137.  *
  138.  * DevBlockDeviceHandle routine blockIOProc calling sequence:
  139.  *
  140.  *  ReturnStatus blockIOProc(blockDevHandlePtr, requestPtr)
  141.  *       DevBlockDeviceHandle    *blockDevHandlePtr;
  142.  *                    / * Handle of the device to operate on. * /
  143.  *     DevBlockDeviceRequest    *requestPtr; / * Request to be performed. * /
  144.  *
  145.  *    Enqueue a block IO request for the specified device. Upon operation
  146.  *    completion doneProc specified in the requestPtr is called. 
  147.  *    blockIOProc should return SUCCESS if the operation is 
  148.  *    successfully enqueued or a Sprite error code otherwise. 
  149.  *    When the enqueued operation finishes, 
  150.  *    doneProc is called with the following arguments:
  151.  *
  152.  *    (*doneProc)(requestPtr, returnStatus, amountTransferred)
  153.  *        DevBlockDeviceRequest *requestPtr;
  154.  *                           / * The requestPtr passed to
  155.  *                         * blockIOProc. * /
  156.  *        ReturnStatus    returnStatus;  / * The error status of the
  157.  *                         * command. SUCCESS if no
  158.  *                         * error occurred. * /
  159.  *        int    amountTransferred;     / * The number of bytes
  160.  *                         * transferred by the 
  161.  *                         * operation. * /
  162.  *    
  163.  *    Note that doneProc may be called before blockIOProc finishes and
  164.  *    may also be called running at interrupt level. 
  165.  *
  166.  * IOControlProc calling sequences:
  167.  *     ReturnStatus IOControlProc(blockDevHandlePtr, command, byteOrder,
  168.  *                inBufSize, inBuffer,  outBufSize, outBuffer);
  169.  *
  170.  *       DevBlockDeviceHandle    *blockDevHandlePtr;
  171.  *                    / * Handle of the device to operate on. * /
  172.  *     int    command;    / * IO control to be performed. * /
  173.  *     int    byteOrder;    / * Caller's byte ordering. * /
  174.  *     int    inBufSize;    / * Size of the input buffer - inBuffer. * /
  175.  *     Address inBuffer;    / * The input buffer. * /
  176.  *     int    outBufSize;    / * Size of the output buffer - outBuffer. * /
  177.  *     Address outBuffer;    / * The output buffer. * /
  178.  *    
  179.  *    Execute an IO control operation on the specified device. The
  180.  *    return value is the Sprite error code for the IOControl.
  181.  *
  182.  *
  183.  *----------------------------------------------------------------------
  184.  */
  185.  
  186. /*
  187.  * DEV_NO_ATTACH_PROC -  Special attach procedure entry in the
  188.  *             devFsOpTable array  specifying no attach proc 
  189.  *             available.
  190.  */
  191. #define    DEV_NO_ATTACH_PROC    ((DevBlockDeviceHandle *(*)(Fs_Device *))0)
  192.  
  193. /* procedures */
  194.  
  195. extern DevBlockDeviceHandle *Dev_BlockDeviceAttach _ARGS_((Fs_Device *devicePtr));
  196. extern ReturnStatus Dev_BlockDeviceRelease _ARGS_((DevBlockDeviceHandle *blockDevHandlePtr));
  197. extern ReturnStatus Dev_BlockDeviceIOSync _ARGS_((DevBlockDeviceHandle *blockDevHandlePtr, DevBlockDeviceRequest *requestPtr, int *amountTransferredPtr));
  198.  
  199. #ifdef lint
  200. extern ReturnStatus Dev_BlockDeviceIO _ARGS_ ((DevBlockDeviceHandle *
  201.     blockDevHandlePtr, DevBlockDeviceRequest *requestPtr));
  202. extern ReturnStatus Dev_BlockDeviceIOControl _ARGS_ ((DevBlockDeviceHandle
  203.     *blockDevHandlePtr, Fs_IOCParam *ioctlPtr, Fs_IOReply *replyPtr));
  204. #else
  205. /*
  206.  * For speed, we code Dev_BlockDeviceIO and Dev_BlockDeviceIOControl as 
  207.  * macros. See the routines in devBlockDevice.c for documentation. If 
  208.  * lint is being run we keep around the routines for type checking.
  209.  */
  210. #define    Dev_BlockDeviceIO(handlePtr, requestPtr) \
  211.        (((handlePtr)->blockIOProc)((handlePtr),(requestPtr)))
  212.  
  213. #define    Dev_BlockDeviceIOControl(handle, ioctlPtr, replyPtr) \
  214.        (((handle)->IOControlProc)((handle),(ioctlPtr), (replyPtr)))
  215.  
  216.  
  217. #endif /* lint */
  218. #endif /* _DEVBLOCKDEVICE */
  219.